<#import "../_features.html" as f>

<@f.scaffold title="@FieldNameConstants" logline="Name... that... field! String constants for your field's names.">
	<@f.history>
		<p>
			@FieldNameConstants was introduced as experimental feature in lombok v1.16.22.
		</p><p>
			@FieldNameConstants was redesigned in lombok v1.18.4.
		</p><p>
			The <em>lombok.config</em> option <code>lombok.fieldNameConstants.uppercase = true</code> was added in lombok v1.18.8.
		</p>
	</@f.history>

	<@f.experimental>
		<ul>
			<li>
				New feature; unsure if this busts enough boilerplate.
			</li>
		</ul>
		Current status: <em>neutral</em> - As a just-introduced feature we're still gathering feedback.
	</@f.experimental>

	<@f.overview>
		<p>
			The <code>@FieldNameConstants</code> annotation generates an inner type which contains 1 constant for each field in your class; either string constants (fields marked <code>public static final</code>, of type <code>java.lang.String</code>) or if you prefer, an enum type with 1 value for each field - write <code>@FieldNameConstants(asEnum = true)</code> for the enum variant. <code>@FieldNameConstants</code> is useful for various marshalling and serialization frameworks. The constant field (whether enum value or string constant) always has the exact same name as the field, capitalization and all, unless you set the <code>lombok.fieldNameConstants.uppercase = true</code> option in your <code>lombok.config</code> file; in that case lombok will try to <code>UPPER_CASE</code> the name.
		</p><p>
			The generated inner type is by default called <code>Fields</code> and is <code>public</code>. You can modify this via <code>@FieldNameConstants(innerTypeName = "FieldNames", level = AccessLevel.PACKAGE)</code> for example. The default inner type name can also be modified via configuration key <code>lombok.fieldNameConstants.innerTypeName</code>. The generated fields are always <code>public</code>.
		</p><p>
			Must be applied to classes (or enums, though you'd rarely want to do that). By default includes all non-transient, non-static fields. You can use <code>@FieldNameConstants.Include</code> in fields + <code>@FieldNameConstants(onlyExplicitlyIncluded = true)</code>, or <code>@FieldNameConstants.Exclude</code> for more fine-grained control.
		</p>
	</@f.overview>

	<@f.snippets name="experimental/FieldNameConstants" />

	<@f.confKeys>
		<dt>
			<code>lombok.fieldNameConstants.flagUsage</code> = [<code>warning</code> | <code>error</code>] (default: not set)
		</dt><dd>
			Lombok will flag any usage of <code>@FieldDefaults</code> as a warning or error if configured.
		</dd><dt>
			<code>lombok.fieldNameConstants.innerTypeName</code> = <em>a string</em> (default: 'Fields')
		</dt><dd>
			The name of the inner type generated by lombok can be controlled with this configuration key.
		</dd><dt>
			<code>lombok.fieldNameConstants.uppercase</code> = [<code>true</code> | <code>false</code>] (default: false)
		</dt><dd>
			If <code>true</code>, attempt to uppercase the generated fields.
		</dd>
	</@f.confKeys>

	<@f.smallPrint>
		<p>
			Starting with lombok v1.18.6, lombok will silently skip generating anything that already exists. You can define the inner <code>Fields</code> enum/class yourself,
			in which case lombok will add all the enum constants / public static final fields you haven't written yourself.
		</p><p>
			From lombok v1.16.22 to lombok v1.18.2, this feature generated constants inside the type directly; the name of these fields would for example turn field <code>exampleFieldName</code> into <code>public static final String FIELD_EXAMPLE_FIELD_NAME = "exampleFieldName";</code>. The prefix and suffix (here, <code>FIELD_</code>, and the empty string) were configurable. Starting with lombok v1.18.4 this feature has been redesigned into generating an inner type as described above.
		</p><p>
			Any parameters of lombok annotations that take strings need to be supplied actual string literals; you cannot have references to constants like those generated by <code>@FieldNameConstants</code>. If you'd like to use <code>@FieldNameConstants</code> to for example fill in the <code>of</code> and/or <code>exclude</code> parameters of <code>@ToString</code> and similar lombok annotations, use the <code>@ToString.Include</code> / <code>@ToString.Exclude</code> etc system instead; these are described at the feature pages for those features.
		</p><p>
			Like other lombok handlers that touch fields, any field whose name starts with a dollar (<code>$</code>) symbol is skipped entirely. Such a field will not be modified at all. Static fields are also skipped.
		</p><p>
			<em>MapStruct interop:</em> When making references to field name constants inside MapStruct's <code>@Mapping</code>, and you use that annotation more than once on a node, you must manually wrap these in the <code>@Mappings</code> 'container annotation'. Like so: <code>@Mappings({@Mapping(target = Entity.Fields.entityProperty, source = "dtoProperty")})</code>.
		</p>
	</@f.smallPrint>
</@f.scaffold>
